Express Compression JPEG Application Program Interface (ECJAPI)

(c) 1993 Expressed Compression Laboratories
********************************************************************************

ECJ_Decode (1.x)
--------------------------------------------------------------------------------
#include "ecjapi.h"

HANDLE ECJ_Decode( lpstrfilename, wParam, lParam, lpfnECJ_CallBack )

LPSTR	lpstrFileName;		/* name of file to decode */
WORD	wParam;			/* attributes */
LONG	lParam;			/* reserved */
ECJCB	lpfnECJ_CallBack;	/* call back routine */

ECJ_Decode decodes the specified JPEG file and returns a device independent
bitmap (DIB).

Parameter	 Description
---------------------------------------------------------------------------
lpstrFileName	 Points to a null-terminated string that names the JPEG
		 file to be decoded.

wParam		 Specifies how to proceed with the decoding. This parameter
		 can be a combination of the following values.

		 Value		Meaning
		 -------------- -------------------------------------------
		 ECJ_GRAY_ONLY	Create a gray only DIB.
		 ECJ_24_BITS	Create a 24 bit DIB.
		 ECJ_2_PASS	Use two-pass 24 to 8 bit colour quantisation.
		 ECJ_DITHER	Use FS dithering in two-pass color quantisation.
		 ECJ_HALF_SIZE	Shrink the dimensions of the picture by half.
		 ECJ_AUTO_HALF	Automatically shrink the dimensions of the
				picture by half when appropriate.

		 ECJ_DITHER can only be used in conjunction with ECJ_2_PASS.
		 ECJ_GRAY_ONLY, ECJ_24_BITS and ECJ_2_PASS are mutually
		 exclusive. ECJ_AUTO_HALF takes precedence over ECJ_HALF_SIZE.
		 By default (with wParam = 0) ECJ_Decode creates an 8 bit DIB,
		 using single pass colour quantisation with ordered dithering
		 when appropriate.

lParam		 Reserved.

lpfnECJ_CallBack Specifies the procedure-instance address of the callback
		 procedure. ECJ_Decode sends messages and periodically passes
		 control back to the client via the ECJ callback procedure.
		 Setting this parameter to NULL disables the callback
		 mechanism.
		 For more information see the description of the ECJ_CallBack
		 function.

Returns
=======
The return value is the handle to the DIB if the function is successful.
Otherwise, it is NULL.

See Also
========
ECJ_CallBack

********************************************************************************

ECJ_DecodeMem (1.x)
--------------------------------------------------------------------------------
#include "ecjapi.h"

HANDLE ECJ_DecodeMem( hStream, dwStreamLen, wParam, lParam, lpfnECJ_CallBack )

HGLOBAL	hStream;		/* handle to bitstream in memory */
DWORD	dwStreamLen;		/* size of bitstream in bytes */
WORD	wParam;			/* attributes */
LONG	lParam;			/* reserved */
ECJCB	lpfnECJ_CallBack;	/* call back routine */

ECJ_DecodeMem decodes the specified JPEG file and returns a device independent
bitmap (DIB). ECJ_DecodeMem is essentially the same as ECJ_Decode, except
that instead of taking a filename it takes a memory object as input.

Parameter	 Description
---------------------------------------------------------------------------
hStream		 Global handle to memory object containing bitstream
		 to be decoded.

dwStreamLen	 Size of the bitstream in bytes.

See ECJ_Decode for explanations on the rest of the parameters.

********************************************************************************

ECJ_CallBack (1.x)
--------------------------------------------------------------------------------
#include "ecjapi.h"

int CALLBACK ECJ_CallBack( mMsg, wParam, lParam )

WORD	mMsg;	/* message */
WORD	wParam;	/* first message parameter */
LONG	lParam;	/* second message parameter */

The ECJ_CallBack function is an application-defined callback function that
processes messages sent by ECJ_Decode.

Parameter	Description
--------------------------------------------------------------------------
mMsg		Specifies the message.

		Message		Meaning
		-----------------------------------------------------------
		ECJ_RESOLUTION	Upon decoding the header of the image
				ECJ_Decode returns with the following
				information:

				Parameter   Bits   Meaning
				-------------------------------------------
				lParam	    0-15   Vertical dimension.
				lParam	   15-32   Horizontal dimension.
				wParam	    0-2    Video format.
						   0 = Y;
						   1 = YUV422;
						   2 = YUV411;
						   3 = YUV444;
				wParam	     3     Picture shrunk by half.

		ECJ_PROGRESS	ECJ_Decode periodically returns control to
				the client with progress information:

				wParam	Stage
				------  ----------------------------------
				0	Pass 1
				1	Creating histogram
				2	Pass 2

				For stages 0 and 2, lParam indicates percentage
				completion.

		ECJ_ERROR	An error has occured. wParam identifies the
				particular error.

				wParam	Error
				---------------------------------------------
				 1	File is not JPEG.
				 2	Can't open file.
				 3	Unexpected EOF.
				 4	Out of memory.
				 5	Unrecognised video format.
				 6	Unexpected scan component.
				 7	Unexpected marker.
				 8	Unexpected RST.
				 9	Unsupported precision.
				10	User abort.

wParam		Message-dependent information.

lParam		More message-dependent information.

Returns
=======
To continue decoding a value of 0 shall be returned.
A return value of -1 instructs ECJ_Decode to abort decoding immediately.

Comments
========
The client does not have to process any of the messages. The simplest
ECJ_CallBack function can simply return 0. A more well behaved application
should take the opportunity to momentarily pass control back to Windows
to achieve non-preemptive multitasking.

See Also
========
ECJ_Decode